Midaspay Checkout SDK

SDK Overview

Launch available payment channels through Midaspay after order placement to provide seamless checkout experience.

The Checkout SDK supports multiple display modes and provides real-time payment status feedback through event callbacks.

Checkout Flow

1. After the user browses and places an order on the merchant's site, the merchant backend sends an order creation request to Midaspay.
2. Upon receiving the request, Midaspay creates an order and returns a redirect_url.
3. Midaspay offers multiple checkout modes. The merchant can choose between redirect checkout or embedded checkout:
   • Redirect Checkout: Redirect the user's browser to the Midaspay hosted checkout page.
   • Embedded Checkout: Integrate the Midaspay JS SDK on the merchant's frontend, call the init method to initialize and render the checkout interface within the merchant's page. This document describes how to integrate the Embedded Checkout SDK.
4. After the user completes the payment, the checkout page will display the payment result to the user, and Midaspay will notify the merchant server of the payment result asynchronously.

Installation

Include the script in your HTML file:

Sandbox Environment:

<script src="https://sandbox-page.centauriglobal.com/frontend/static/midas-checkout-sdk.min.js"></script>

Production Environment:

<script src="https://cdn.harvestsharp.com/frontend/static/midas-checkout-sdk.min.js"></script>

API Reference

Initialization

Initialize the SDK by calling MidasCheckoutSDK.init() with a configuration object:

MidasCheckoutSDK.init({
    url: 'YOUR_CHECKOUT_URL',
    type: 'overlay',
    onEvents: (res) => {
        console.log('Event received:', res);
    }
});

Parameters

Parameter	Type	Required	Description
url	string	Yes	The checkout URL provided by Midaspay backend. This URL contains authentication token, order information, and configuration parameters.
type	string	Yes	Display type of the checkout interface. Use 'overlay' to show a modal popup over your page.
container	string	No	The container element ID where the SDK will render. Required when type=inline.
onEvents	function	Yes	Callback function to handle SDK events. Receives an event object with action status, order information, and error codes.

Events

The onEvents callback receives event objcallback receives event objects with the following structure.

Note: All event field values (action, status, result_code)ects with the following structure.

Note: All event field values (action, status, result_code) are guaranteed to be lowercase. The SDK normalizes these fields automatically, even if the underlying source returns uppercase values.

Initialization Events

Event Action	Description	Example Response
init_sdk	SDK initialization started	{ action: 'init_sdk' }
init_sdk_success	SDK initialized successfully	{ action: 'init_sdk_success' }
init_sdk_failed	SDK initialization failed (query order failed)	{ action: 'init_sdk_failed', result_code: 'query_order_failed' }
init_sdk_failed	SDK initialization failed (query channel failed)	{ action: 'init_sdk_failed', result_code: 'query_channel_failed' }

Loading Events

Event Action	Description	Example Response
set_loading	Show loading indicator	{ action: 'set_loading' }
reset_loading	Hide loading indicator	{ action: 'reset_loading' }

Payment Events

Event Action	Description	Example Response
payment_success	Payment completed successfully	{ order_id: '20250313093459113176592', action: 'payment_success' }
payment_failed	Payment initialization failed	{ action: 'payment_failed', result_code: 'pay_token_failed' }
payment_failed	Card hash retrieval failed	{ action: 'payment_failed', result_code: 'get_card_hash_failed' }
payment_processing	Payment status unknown; polling required	{ order_id: '20250313093459113176592', action: 'payment_processing' }

Overlay Events

Event Action	Description	Example Response
close_overlay	Overlay closed by user or SDK	{ action: 'close_overlay' }

Event Handling Example:

onEvents: (res) => {
    switch (res.action) {
        case 'init_sdk':
            console.log('SDK initializing...');
            break;
        case 'init_sdk_success':
            console.log('SDK ready');
            break;
        case 'init_sdk_failed':
            console.error('SDK initialization failed:', res.result_code);
            // Handle initialization failure
            break;
        case 'set_loading':
            // Show your custom loading indicator
            break;
        case 'reset_loading':
            // Hide your custom loading indicator
            break;
        case 'payment_success':
            console.log('Payment successful, order:', res.order_id);
            // Redirect to success page or update UI
            break;
        case 'payment_failed':
            console.error('Payment failed:', res.result_code);
            // Display error message to user
            break;
        case 'payment_exception':
            console.error('Payment exception:', res.result_code, 'Debug ID:', res.debug_id);
            // Log error and notify user
            break;
        case 'payment_processing':
            console.log('Payment processing, order:', res.order_id);
            // Poll order status from your backend to get final result
            break;
        case 'close_overlay':
            console.log('Overlay closed');
            // Handle overlay close event
            break;
        default:
            console.error('Unknown event:', res);
            break;
    }
}

Methods

MidasCheckoutSDK.init(config)

Initializes the SDK with the provided configuration. Must be called before any other SDK methods.

Parameters:

• config (Object): Configuration object containing initialization parameters.

Returns: void

---

MidasCheckoutSDK.checkout()

Opens the checkout overlay popup. Call this method when the user initiates the payment process (e.g., clicking a checkout button).

Parameters: None

Returns: void

Usage:

// Trigger checkout on button click
document.getElementById('checkout-btn').addEventListener('click', () => {
    MidasCheckoutSDK.checkout();
});

Usage Guide

Step 1: Include the SDK

Add the SDK script to your HTML file before your application code.

    <!-- Sandbox development -->
    <script src="https://sandbox-page.centauriglobal.com/frontend/static/midas-checkout-sdk.min.js"></script>
    <!-- Production CDN -->
    <!--<script src="https://cdn.harvestsharp.com/frontend/static/midas-checkout-sdk.min.js"></script>-->

Step 2: Initialize the SDK

Call MidasCheckoutSDK.init() with your configuration after the page loads.

Step 3: Trigger Checkout

Call MidasCheckoutSDK.checkout() when the user is ready to start the payment process.

Step 4: Handle Events

Implement the onEvents callback to handle payment results and update your UI accordingly.

Note: When receiving a payment_processing event, the payment channel did not return a result, so the SDK cannot confirm the payment status. You must poll your backend to check the final order status.

Error Codes

Result Code	Description
query_order_failed	Failed to query order information during initialization
query_channel_failed	Failed to query available payment channels
pay_token_failed	Failed to initialize payment token
get_card_hash_failed	Failed to retrieve card hash for payment

Checkout Demo

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Midas SDK Demo</title>
    <style>
        * {
            margin: 0;
            padding: 0;
        }
        html, body {
            width: 100%;
            height: 100%;
        }
        html {
            background: #eeeeee;
            background-size: cover;
        }
        h1 {
            text-align: center;
            color: black;
            margin: 0.5em 0;
        }
        .btn-group {
            text-align: center;
            margin-top: 3em;
        }
        button {
            padding: 0.5em 1em;
            font-size: 18px;
            border-radius: 8px;
            border: none;
            cursor: pointer;
            background: #007bff;
            color: white;
        }
        button:hover {
            background: #0056b3;
        }
    </style>
    <!-- Sandbox development -->
    <script src="https://sandbox-page.centauriglobal.com/frontend/static/midas-checkout-sdk.min.js"></script>
    <!-- Production CDN -->
    <!--<script src="https://cdn.harvestsharp.com/frontend/static/midas-checkout-sdk.min.js"></script>-->
    <script>
        MidasCheckoutSDK.init({
            url: 'YOUR_CHECKOUT_URL', // Checkout URL with token
            type: 'overlay',
            onEvents: (res) => {
                console.log('onEvents: ', res);

                // Initialization events
                // { action: 'init_sdk' }
                // { action: 'init_sdk_success' }
                // { action: 'init_sdk_failed', result_code: 'query_order_failed' }
                // { action: 'init_sdk_failed', result_code: 'query_channel_failed' }

                // Loading events
                // { action: 'set_loading' }
                // { action: 'reset_loading' }

                // Payment events
                // { action: 'payment_failed', result_code: 'pay_token_failed' }
                // { action: 'payment_exception', result_code: '...', debug_id: '...' }
                // { action: 'payment_failed', result_code: 'get_card_hash_failed' }
                // { order_id: '20250313093459113176592', action: 'payment_success' }
                // { order_id: '20250313093459113176592', action: 'payment_processing' }

                // Overlay events
                // { action: 'close_overlay' }
            }
        });

        const checkout = () => {
            MidasCheckoutSDK.checkout();
        };
    </script>
</head>
<body>
    <h1>Midas SDK Demo - Overlay</h1>
    <div class="btn-group">
        <button onclick="checkout()">Checkout Overlay</button>
    </div>
</body>
</html>